//
//  DMAdapterProtocol.h
//  DualMediationSDK
//
//  Created by AI Assistant
//  Copyright © 2024 YourCompany. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import "../Core/DMAdConfig.h"
#import "../Models/DMUserConsent.h"

NS_ASSUME_NONNULL_BEGIN

@protocol DMAdapterProtocol;
@class DMAdResponse;

@protocol DMAdapterProtocol;
@class DMAdResponse;

/**
 * 适配器事件委托协议
 */
@protocol DMAdapterDelegate <NSObject>

@required
/**
 * 广告加载成功
 * @param adapter 适配器实例
 * @param response 广告响应
 * @param adType 广告类型
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didLoadAdWithResponse:(DMAdResponse *)response adType:(DMAdType)adType;

/**
 * 广告加载失败
 * @param adapter 适配器实例
 * @param error 错误信息
 * @param adType 广告类型
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didFailToLoadAdWithError:(NSError *)error adType:(DMAdType)adType;

/**
 * 广告展示成功
 * @param adapter 适配器实例
 * @param adId 广告ID
 * @param adType 广告类型
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didShowAdWithId:(NSString *)adId adType:(DMAdType)adType;

/**
 * 广告展示失败
 * @param adapter 适配器实例
 * @param adId 广告ID
 * @param error 错误信息
 * @param adType 广告类型
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didFailToShowAdWithId:(NSString *)adId error:(NSError *)error adType:(DMAdType)adType;

/**
 * 广告被点击
 * @param adapter 适配器实例
 * @param adId 广告ID
 * @param adType 广告类型
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didClickAdWithId:(NSString *)adId adType:(DMAdType)adType;

/**
 * 广告被关闭
 * @param adapter 适配器实例
 * @param adId 广告ID
 * @param adType 广告类型
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didCloseAdWithId:(NSString *)adId adType:(DMAdType)adType;

@optional
/**
 * 激励视频广告奖励发放
 * @param adapter 适配器实例
 * @param adId 广告ID
 * @param reward 奖励信息
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didRewardUserWithId:(NSString *)adId reward:(NSDictionary *)reward;

/**
 * 广告收入信息（用于竞价）
 * @param adapter 适配器实例
 * @param adId 广告ID
 * @param revenue 收入信息
 */
- (void)adapter:(id<DMAdapterProtocol>)adapter didReceiveRevenueWithId:(NSString *)adId revenue:(NSDictionary *)revenue;

@end

/**
 * 聚合平台适配器统一协议
 * 
 * 核心职责：
 * 1. 统一广告加载和展示接口
 * 2. 隔离不同聚合平台的实现细节
 * 3. 标准化事件回调和数据格式
 * 4. 支持竞价和兜底机制
 */
@protocol DMAdapterProtocol <NSObject>

#pragma mark - Required Properties

/**
 * 适配器名称（如"MAX", "IronSource"）
 */
@property (nonatomic, readonly) NSString *adapterName;

/**
 * 适配器版本
 */
@property (nonatomic, readonly) NSString *adapterVersion;

/**
 * 底层SDK版本
 */
@property (nonatomic, readonly) NSString *underlyingSDKVersion;

/**
 * 是否已初始化
 */
@property (nonatomic, readonly) BOOL isInitialized;

/**
 * 事件委托
 */
@property (nonatomic, weak, nullable) id<DMAdapterDelegate> delegate;

#pragma mark - Required Methods - Initialization

/**
 * 初始化适配器
 * @param config 配置参数
 * @param completion 完成回调
 */
- (void)initializeWithConfig:(NSDictionary *)config
                  completion:(void(^)(BOOL success, NSError * _Nullable error))completion;

/**
 * 设置用户同意状态
 * @param consent 用户同意信息
 */
- (void)setUserConsent:(DMUserConsent *)consent;

/**
 * 设置调试模式
 * @param enabled 是否启用
 */
- (void)setDebugMode:(BOOL)enabled;

/**
 * 设置测试设备
 * @param deviceIds 测试设备ID列表
 */
- (void)setTestDeviceIds:(NSArray<NSString *> *)deviceIds;

#pragma mark - Required Methods - Ad Loading

/**
 * 加载Banner广告
 * @param request 广告请求
 * @param adSize 广告尺寸
 * @return 广告视图（同步返回，广告内容异步加载）
 */
- (nullable UIView *)loadBannerAdWithRequest:(DMAdRequest *)request adSize:(CGSize)adSize;

/**
 * 加载插屏广告
 * @param request 广告请求
 */
- (void)loadInterstitialAdWithRequest:(DMAdRequest *)request;

/**
 * 加载激励视频广告
 * @param request 广告请求
 */
- (void)loadRewardedAdWithRequest:(DMAdRequest *)request;

/**
 * 加载原生广告
 * @param request 广告请求
 */
- (void)loadNativeAdWithRequest:(DMAdRequest *)request;

#pragma mark - Required Methods - Ad Showing

/**
 * 展示插屏广告
 * @param adId 广告ID
 * @param viewController 展示的视图控制器
 */
- (void)showInterstitialAdWithId:(NSString *)adId viewController:(UIViewController *)viewController;

/**
 * 展示激励视频广告
 * @param adId 广告ID
 * @param viewController 展示的视图控制器
 */
- (void)showRewardedAdWithId:(NSString *)adId viewController:(UIViewController *)viewController;

#pragma mark - Required Methods - Ad Management

/**
 * 检查广告是否准备就绪
 * @param adId 广告ID
 */
- (BOOL)isAdReadyWithId:(NSString *)adId;

/**
 * 销毁广告
 * @param adId 广告ID
 */
- (void)destroyAdWithId:(NSString *)adId;

/**
 * 销毁所有广告
 */
- (void)destroyAllAds;

#pragma mark - Optional Methods - Advanced Features

@optional

/**
 * 预加载广告
 * @param request 广告请求
 * @param completion 完成回调
 */
- (void)preloadAdWithRequest:(DMAdRequest *)request
                  completion:(void(^)(BOOL success, NSString * _Nullable adId, NSError * _Nullable error))completion;

/**
 * 获取广告的eCPM信息（用于竞价）
 * @param adId 广告ID
 */
- (nullable NSNumber *)getECPMForAdId:(NSString *)adId;

/**
 * 获取广告的填充率信息
 * @param placementId 广告位ID
 * @param adType 广告类型
 */
- (nullable NSNumber *)getFillRateForPlacementId:(NSString *)placementId adType:(NSString *)adType;

/**
 * 设置服务器端竞价参数
 * @param parameters 竞价参数
 */
- (void)setServerSideBiddingParameters:(NSDictionary *)parameters;

/**
 * 获取竞价令牌
 * @param request 广告请求
 * @param completion 完成回调
 */
- (void)getBiddingTokenForRequest:(DMAdRequest *)request
                       completion:(void(^)(NSString * _Nullable token, NSError * _Nullable error))completion;

#pragma mark - Optional Methods - Analytics

@optional

/**
 * 获取广告统计数据
 * @param placementId 广告位ID（可选）
 * @param adType 广告类型（可选）
 */
- (NSDictionary *)getAnalyticsDataForPlacementId:(nullable NSString *)placementId adType:(nullable NSString *)adType;

/**
 * 设置自定义事件追踪
 * @param eventName 事件名称
 * @param parameters 事件参数
 */
- (void)trackCustomEvent:(NSString *)eventName parameters:(nullable NSDictionary *)parameters;

#pragma mark - Optional Methods - Utilities

@optional

/**
 * 获取支持的广告类型列表
 */
- (NSArray<NSString *> *)getSupportedAdTypes;

/**
 * 获取支持的广告尺寸列表
 */
- (NSArray<NSValue *> *)getSupportedAdSizes;

/**
 * 检查特定功能是否支持
 * @param feature 功能名称
 */
- (BOOL)supportsFeature:(NSString *)feature;

/**
 * 获取SDK配置信息
 */
- (NSDictionary *)getSDKConfiguration;

/**
 * 设置额外的网络配置
 * @param networkName 网络名称
 * @param config 配置参数
 */
- (void)setNetworkConfiguration:(NSString *)networkName config:(NSDictionary *)config;

@end

NS_ASSUME_NONNULL_END 